home *** CD-ROM | disk | FTP | other *** search
/ MacFormat 1994 November / macformat-018.iso / Utility Spectacular / Developer / CIncludesTool 1.0 / original version / Instructions < prev   
Encoding:
Text File  |  1990-07-30  |  4.1 KB  |  117 lines  |  [TEXT/MPS ]
  1. Instructions for use of CIncludesTool    -- John Jeppson
  2.  
  3. Changes in this version - 07/29/90.
  4.     1. Adds ability to open CIncludes header file where target word is defined.
  5.     2. Corrects bug which intermittently caused "reformat" instruction to fail.
  6.     
  7.  
  8. Description:
  9.  
  10.     CIncludesTool is an MPW tool which locates a C or C++ identifier in
  11.     the {CIncludes} file where it is first used.  The tool then generates
  12.     the appropriate "#include <file>" instruction for your program.  A
  13.     dictionary of all the indentifiers is generated and stored in
  14.     your system folder, so using the tool is quite efficient.
  15.     
  16.     The tool has three main actions:
  17.     
  18.         1. Generate "#include <file>" instruction for the selected identifier.
  19.         
  20.         2. Consolidate several #include instructions, eliminating dependencies.
  21.         
  22.         3. Open the CInclude file to the spot where an identifier is defined.
  23.                 *** thanks to Daniel Grassi for this part ***
  24.     
  25.  
  26.     CIncludesTool is supplied as source code which you may modify and use
  27.     on your own system.  The accompanying source code files are Copyright
  28.     1990 by John Jeppson and may not be sold or distributed for profit
  29.     without my permission.  
  30.     
  31.     
  32. Installation:
  33.  
  34.     1. Build "CIncludesCode" using the enclosed ".make" file.
  35.  
  36.     2. Drag the resulting "CIncludesCode" file to your MPW {tools} folder.
  37.  
  38.     3. Drag the script file "CIncludesTool" to your MPW {tools} folder.
  39.  
  40.     4. From your worksheet execute: "CIncludesTool -m". This command generates
  41.         the indentifier dictionary and saves it in your system folder in a
  42.         file called "CIncludesData".  If you change the files in your
  43.         {CIncludes} folder then repeat this step.
  44.         
  45.     5. Create menu/keyboard commands for the tool by placing the following
  46.         instructions in your "UserStartup" file:
  47.  
  48.             AddMenu Edit 'CIncludesLocate/0'           'CIncludesTool -f'
  49.             AddMenu Edit 'CIncludesReformat/9'        'CIncludesTool -i'
  50.             AddMenu Edit 'CIncludesOpenHeader/8'     'CIncludesTool -d'
  51.  
  52.         Note that these commands use Cmd-0, Cmd-9, and Cmd-8 as the keyboard
  53.         equivalents.  Change them to whatever you want. (I actually use
  54.         Cmd-D instead of Cmd-8, replacing the "open selection" command in
  55.         the file menu.)
  56.         
  57.         
  58. Usage:
  59.  
  60.     When the C or C++ compiler complains that a Mac toolbox name or
  61.     other "system" identifier is undefined, select the indentifier
  62.     in your program text and press "Cmd-0". The appropriate "#include"
  63.     instruction will be inserted at the top of your program text file in
  64.     the active window.
  65.     
  66.     A series of "#include" instructions may be condensed by eliminating
  67.     duplicates and dependencies. Just select all the lines containing
  68.     "#include" instructions and press Cmd-9.
  69.     
  70.     To open the appropriate header file where something is defined, select
  71.     the identifier and press Cmd-8.
  72.     
  73.     
  74. Internals:
  75.  
  76.     The file "CIncludesTool" is an MPW script which must be called with
  77.     a single parameter:
  78.     
  79.         -m  Rebuilds the CIncludes identifier dictionary.
  80.         -f  Locates selection from active window.
  81.         -i  Reformates "include" statements in {Active}.§ 
  82.         -d  Opens header file where selection is defined.
  83.  
  84.  
  85.     "CIncludesTool" script, in turn, calls "CIncludesCode", an MPW tool
  86.     written in C, supplying various parameters.  {1} must be: 
  87.  
  88.         -m  Rebuilds the CIncludes identifier dictionary file
  89.         -v  Checks if {2} is a valid C identifier string
  90.         -f  Attempts to locate {2} in identifier dictionary
  91.         -i  Reformates "include" statements in {Active}.§ 
  92.         -d  Gets file name and position where selection is defined.
  93.     
  94.  
  95.     "CIncludesCode" writes error messages, if any, to StdErr.
  96.     Also:
  97.  
  98.         (-m) writes progress messages to StdErr so that
  99.                 they will be displayed when written.
  100.  
  101.         (-f) writes output to {Active} window at the window top (or
  102.                 to the next line if you comment out the appropriate
  103.                 line in "CIncludesTool" script).  
  104.  
  105.         (-i) replaces selection in active window with list of
  106.                 include statements. Any comments following
  107.                 previous include statements will be lost.
  108.     
  109.  
  110.     "CIncludesCode" also returns one of the following status codes:
  111.  
  112.         0    Okay
  113.         1    Bad Parameters
  114.         2    Invalid identifier string in {2}
  115.         3    Out of Memory
  116.         4    Unable to locate identifier {2} in dictionary
  117.